docs(pm-dispatch): read the verify-lock queue depth before each dispatch and hold at depth ≥ 2 (#14944 Q1 B) - #16271

Part of #14944.

Implements the Q1 B half of the maintainer ruling recorded on the card (comment 5548762263, director seat, 2026-09-05, maintainer 「同意」). The card does not close on this PR — it closes on the one-week --report re-measure the ruling asks for. The Q3 A half (the dev waiting discipline in .claude/agents/os-dev.md) is the domain:skills lane's: #16262 remains open and is not touched here.

The ruling (quoted)

Q1 = B. The nominal cap of 5 (the 2026-09-03 ruling) is unchanged. Before the N-th dispatch the PM loop reads scripts/pm/os-verify-lock.sh --status; if the queue depth (arriving run included) would be ≥ 2, the dispatch waits — the effective cap is a function of lock width, which is the relationship the cap ruling was made without. Not A (accept ~11% and rising), not C (the number 3 is not the variable; depth is).

Execution: domain:devx seat, S: the depth check in the pm-dispatch loop (.claude/skills/pm-dispatch/** — governed: draft, os-zhuang + hotlong, human merge) with the threshold written as a named constant and its provenance (this card, the depth table); domain:skills seat: the waiting discipline paragraph in the dev contract (same governed path; may ride in the same PR). Re-measure with --report one week after landing and post the exit-99 rate here; the card closes on that reading.

Depth table the ruling adopted (dev measurement 5547089539, 313 ledger records / 35.1 h): exit-99 (NOT MEASURED) rate 1.0% / 22.6% / 36.1% / 55.6% at arrival queue depth 1 / 2 / 3 / 4.

What changes

.claude/skills/pm-dispatch/SKILL.md, 执行座位职责 → 候选与批次, directly under the batch cap line — four rules:

1. Before the N-th dispatch the seat reads scripts/pm/os-verify-lock.sh --status; when the arrival depth would be ≥ LOCK_DEPTH_HOLD (= 2) the dispatch waits.
2. Depth-counting rule (verbatim from the skill): 「到达深度 = queue N: 行数 + 1(待派 dev 的运行算作到达);state: holder 与 parked 行不计。」 — the number of queue N: lines in the --status output, plus one for the run the dev about to be dispatched will bring. The state: holder line and parked N: lines are not counted.
3. The effective cap is a function of lock width, not a second batch; priority:p0 may still exceed batch but does not cross the depth hold.
4. Provenance of the threshold is the depth table (1%/23%/36%/56% at depth 1/2/3/4); while waiting, the slot is left open (not filled by the next card); the reading, UTC-stamped, goes into the claim comment.

The priority:p0 state-table row gains 「深度等待」 among the things queue-jumping does not exempt. references/core-rules.md carries both changes in its one-line form (line 11 and line 39), per the skill's own two-place rule.

Why the holder is not counted. The threshold is defined on the ledger's depth column, which is what the depth table was computed over. That column is read by queue_live | wc -l right after the arriving call mints its own ticket, and a run's ticket is removed at the moment it acquires (rm -f "$TICKET" immediately after HOLDING=1), so the holder is never in queue_live. --report states the same: "queue depth on arrival (the arriving run INCLUDED — 1 means nobody was ahead)". Counting the holder would shift every reading by one and hold at what the table calls depth 1 (1.0% exit-99). The two readings the PM seat already took under this rule (holder + 1 waiter ⇒ hold at 08:31Z; holder + empty queue ⇒ depth 1 ⇒ dispatch at 08:49Z) agree with this counting.

One-liner over --status output, for the seat (no new flag added to the script — --status exposes no machine-readable depth, and widening scripts/pm/** is outside this card's file surface):

W=$(bash scripts/pm/os-verify-lock.sh --status | grep -c '^queue [0-9]*:'); echo "arrival depth = $((W + 1))"

Live reading while writing this, 2026-09-06T08:57:48Z: state: holder pid 4035, held 338s — pnpm --filter '@objectstack/client-react...' build · queue: empty ⇒ waiters 0, arrival depth 1 (below the hold).

Provenance placement. pnpm check:pm-skill-id-lint rejects any # followed by three or more digits in the skill corpus (maintainer ruling 2026-08-12: a rule's provenance lives in the PR that landed it), so the card number cannot appear in the skill text. The in-text provenance is the depth table itself; this PR is where the card is named.

Line ratchet — paid in the same file

All three pm-dispatch files sit at headroom 0. The four added lines are paid by four same-topic merges inside SKILL.md (no rule removed, no ceiling raised, no cross-file move):

Ratchet readings at head 4d3194ba7: SKILL.md is 811 lines (ceiling 811; headroom 0), widest table row is 342 bytes (pin 342; headroom 0); core-rules.md is 150 lines (ceiling 150; headroom 0). Every added or edited prose line is ≤ 120 bytes (max 118 B).

Gates — pinned to head 4d3194ba7

Derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (no paths; change set from the merge base 8adb9e84a): 16 commands, identical to the path-derived list. --ran reconciliation: 16 derived, 16 run, 0 NOT-MEASURED, 0 UNRUN. Exit codes captured by redirect before any pipe.

The last gate first refused with exit 3 PREREQUISITE NOT MET (unbuilt @objectstack/formula / @objectstack/lint — NOT MEASURED, not a red); the prerequisites were built through the shared lock (os-verify-lock: VERDICT command-exit 0 · held the lock 181s · waited 0s, 4 turbo tasks incl. @objectstack/spec) and the gate re-run is the row above.

Note from the derivation tool: the worktree is one commit behind origin/main (6a1e38244, test-shard scripts and ci.yml); that commit touches none of the edited files or the gates above, and the branch is left on the dispatch base so the readings stay pinned to one tree.

Not done here, on purpose

• No flag added to scripts/pm/os-verify-lock.sh (--depth / --json): the file surface of this card is .claude/skills/pm-dispatch/**; the counting rule is the documented one-liner above.
• No line in references/dispatch-runbook.md (headroom 0; the rule and the counting form fit in SKILL.md).
• .claude/agents/os-dev.md untouched — Dev contract: the verify-lock waiting discipline (acquire once, stay blocked, always name OS_VERIFY_LOCK_SLOT) — the #14944 ruling's Q3 A half #16262 remains open.
• No changeset: agent-instruction surface, nothing published (skip-changeset).

Open questions for the maintainer (not decided here)

1. priority:p0 vs the depth hold. The ruling is silent. Written here as: p0 still exceeds batch but does not cross the depth hold — the hold protects gate measurement, and a p0 card gains nothing from a NOT MEASURED gate. Overrule by editing one clause in each of the two files.
2. Where the constant lives. LOCK_DEPTH_HOLD = 2 is named in prose. The skill's existing convention for numbers it reads (CONTRACT_REVIEW_TIER, GOVERNED_APPROVERS) is a single source in scripts/pm/dispatch-gates.mjs / the queue guard. Moving it there is a scripts/pm/** edit — outside this card's declared surface — so it is left in prose; say the word and it becomes a one-line constant plus a pin.
3. batch default. SKILL.md's argument table still lists the batch default as 3 while the ruling calls the nominal cap 5 (2026-09-03). Not changed here (the ruling says the cap is unchanged, not that the default is); flagged for the seat.

维护者速读(草稿)

• 改了什么:PM 派发循环在派第 N 单之前先读共享验证锁的队列(--status),到达深度 ≥ 2 就等,不派;batch 名义上限 5 不变;priority:p0 仍可超 batch,但不越过这个等待。规则同时写进 SKILL.md 与 core-rules.md。
• 为什么改:锁只有一条宽度,实测 NOT MEASURED 率随到达深度 1/2/3/4 从 1% 升到 23%/36%/56%;派发上限与锁宽今天互不相知,多派的 dev 只是在排队烧 token,门禁也没真跑。
• 风险与代价(含回滚):吞吐在锁繁忙时会更保守(有意为之);行数棘轮零增长,四行新增由同文件四处合并付账。回滚 = revert 本 PR,无数据与运行时影响。
• 席位意见:(留空,席位定稿成评论)
• 你要做的:人工合并本 draft PR(受管面);裁定上面三个问题中第 1 条(p0 是否越过深度等待);落地一周后由座位跑 --report 回贴 exit-99 率,卡片以那次读数关闭。

Generated by Claude Code